package lumis.portal.sendmail;

import lumis.portal.PortalException;
import lumis.portal.authentication.SessionConfig;
import lumis.portal.stability.StableMinor;
import lumis.util.ITransaction;

/**
 * Manager that offers send mail service. It also offers capability of sending
 * e-mails asynchronously, by queueing them.
 * 
 * @version $Revision: 13082 $ $Date: 2011-05-27 16:03:12 -0300 (Fri, 27 May 2011) $
 * @since 4.0.4
 */
@StableMinor(version = "6.0", sinceVersion = "4.0")
public interface ISendMailManager
{
	/**
	 * Factory method for creating a new blank mail instance. Use this method to
	 * obtain an instance of {@link ISingleMail}, to fill it with the required
	 * data and use it in the other methods in this manager.
	 * 
	 * @return a new blank mail instance.
	 * @see #createMultipleMail()
	 * @see #createMailAttachment()
	 * @since 4.0.4
	 */
	public ISingleMail createSingleMail() throws PortalException;

	/**
	 * Factory method for creating a new blank mail instance. Use this method to
	 * obtain an instance of {@link IMultipleMail}, to fill it with the
	 * required data and use it in the other methods in this manager.
	 * 
	 * @return a new blank mail instance.
	 * @see #createSingleMail()
	 * @see #createMailAttachment()
	 * @see #createMailDestination()
	 * @since 4.0.4
	 */
	public IMultipleMail createMultipleMail() throws PortalException;

	/**
	 * Factory method for creating a new mail destination instance. Use this
	 * method to obtain an instance of {@link IMailDestination}, to fill it
	 * with the required data and use it in the other methods in this manager.
	 * 
	 * @return a new mail destination instance.
	 * @see #createMultipleMail()
	 * @see IMultipleMail#getDestinations()
	 * @since 4.0.4
	 */
	public IMailDestination createMailDestination() throws PortalException;

	/**
	 * Factory method for creating a new mail attachment instance. Use this
	 * method to obtain an instance of {@link IMailAttachment}, to fill it with
	 * the required data and use it in the other methods in this manager.
	 * 
	 * @return a new mail attachment instance.
	 * @see #createSingleMail()
	 * @see #createMultipleMail()
	 * @see IMailBody#getAttachments()
	 * @since 4.0.4
	 */
	public IMailAttachment createMailAttachment() throws PortalException;

	/**
	 * Returns the IMailConfig containing the configurations for sending
	 * e-mails.
	 * 
	 * @param sessionConfig
	 *            the user session information.
	 * @param transaction
	 *            the transaction for persistence access.
	 * @return the IMailConfig, never null.
	 * @throws PortalException
	 *             if it was not possible to obtain the IMailConfig.
	 * @since 4.0.4
	 */
	public IMailConfig getMailConfig(SessionConfig sessionConfig, ITransaction transaction) throws PortalException;

	/**
	 * Sets the IMailConfig containing the configurations for sending e-mails.
	 * 
	 * @param sessionConfig
	 *            the user session information.
	 * @param mailConfig
	 *            the IMailConfig.
	 * @param transaction
	 *            the transaction for persistence access.
	 * @throws PortalException
	 *             if it was not possible to set the IMailConfig.
	 * @see #getMailConfig(ITransaction)
	 * @since 4.0.4
	 */
	public void setMailConfig(SessionConfig sessionConfig, IMailConfig mailConfig, ITransaction transaction) throws PortalException;

	/**
	 * Sends an e-mail immediately. This method does not garantee rollback of
	 * the e-mail sending as a result of the transaction rollback.
	 * 
	 * @param sessionConfig
	 *            the user session information.
	 * @param mail
	 *            information about the e-mail to be sent.
	 * @param transaction
	 *            the transaction for persistence access.
	 * @throws PortalException
	 *             if it was not possible to send the e-mail.
	 * @see #createSingleMail()
	 * @since 4.0.4
	 */
	public void sendMail(SessionConfig sessionConfig, ISingleMail mail, ITransaction transaction) throws PortalException;

	/**
	 * Adds an e-mail to the send queue. The queue is processed in the
	 * background and the e-mail will be sent when it is processed.
	 * 
	 * @param sessionConfig
	 *            the user session information.
	 * @param mail
	 *            information about the e-mail to be sent.
	 * @param queueId
	 *            the id of the queue where the mail will be added to. If null a
	 *            new queue will be generated. To generate a new queueId use
	 *            {@link #generateNewQueueId()}.
	 * @param transaction
	 *            the transaction for persistence access. If the transaction
	 *            rollbacks the e-mail will not be added to the queue and not
	 *            sent.
	 * @throws PortalException
	 *             if it was not possible to queue the the e-mail.
	 * @see #createSingleMail()
	 * @since 4.0.4
	 */
	public void addMailToSendQueue(SessionConfig sessionConfig, ISingleMail mail, String queueId, ITransaction transaction) throws PortalException;

	/**
	 * Adds an e-mail to the send queue. The queue is processed in the
	 * background and the e-mail will be sent when it is processed.
	 * 
	 * @param sessionConfig
	 *            the user session information.
	 * @param mail
	 *            information about the e-mail to be sent.
	 * @param queueId
	 *            the id of the queue where the mail will be added to. If null a
	 *            new queue will be generated. To generate a new queueId use
	 *            {@link #generateNewQueueId()}.
	 * @param transaction
	 *            the transaction for persistence access. If the transaction
	 *            rollbacks the e-mail will not be added to the queue and not
	 *            sent.
	 * @throws PortalException
	 *             if it was not possible to queue the e-mail.
	 * @see #createMultipleMail()
	 * @since 4.0.4
	 */
	public void addMailToSendQueue(SessionConfig sessionConfig, IMultipleMail mail, String queueId, ITransaction transaction) throws PortalException;

	/**
	 * Verifies the need to create another mail queue process thread, and create
	 * it if necessary. This method is called at regular intervals by the portal
	 * framework to give the manager the opportunity to span processing threads.
	 * 
	 * @throws PortalException
	 *             if it was not possible to complete the operation.
	 * @since 4.0.4
	 */
	public void pollMailQueueProcessing() throws PortalException;

	/**
	 * Returns a new generated queue id.
	 * 
	 * @return a new generated queue id.
	 * @throws PortalException
	 *             if the queue id could not be generated.
	 * @since 4.0.4
	 */
	public String generateNewQueueId() throws PortalException;

	/**
	 * Deletes a mail and all its internal components (body, attachments,
	 * destinations).
	 * 
	 * @param sessionConfig
	 *            the user session information.
	 * @param mailId
	 *            the mail's id.
	 * @param transaction
	 *            the transaction for persistence access.
	 * @throws PortalException
	 *             if it was not possible to delete the mail.
	 * @since 4.0.4
	 */
	public void deleteMail(SessionConfig sessionConfig, String mailId, ITransaction transaction) throws PortalException;
}